---
type: tutorial
title: Write your first Markdown blog post
description: |-
  Tutorial: Build your first Astro blog —
  Add Markdown pages to your site
i18nReady: true
---
import Checklist from '~/components/Checklist.astro';
import Blanks from '~/components/tutorial/Blanks.astro';
import Box from '~/components/tutorial/Box.astro';
import MultipleChoice from '~/components/tutorial/MultipleChoice.astro';
import Option from '~/components/tutorial/Option.astro'
import PreCheck from '~/components/tutorial/PreCheck.astro';
import { Steps } from '@astrojs/starlight/components';
import Badge from "~/components/Badge.astro"

Now that you have built pages using `.astro` files, it's time to make some blog posts using `.md` files!

<PreCheck>
  - Make a new folder and create a new post
  - Write some Markdown content
  - Link to your blog posts on your Blog page
</PreCheck>

## Create your first `.md` file

<Steps>
1. Create a new directory at `src/pages/posts/`. 

2. Add a new (empty) file `post-1.md` inside your new `/posts/` folder.

3. Look for this page in your browser preview by adding `/posts/post-1` to the end of your existing preview URL. (e.g. `http://localhost:4321/posts/post-1`)

4. Change the browser preview URL to view `/posts/post-2` instead. (This is a page you have not yet created.) 

    Note the different output when previewing an "empty" page, and one that doesn't exist. This will help you troubleshoot in the future.
</Steps>

## Write Markdown content

<Steps>
1. Copy or type the following code into `post-1.md`

    ```markdown title="src/pages/posts/post-1.md"
    ---
    title: 'My First Blog Post'
    pubDate: 2022-07-01
    description: 'This is the first post of my new Astro blog.'
    author: 'Astro Learner'
    image:
        url: 'https://docs.astro.build/assets/rose.webp' 
        alt: 'The Astro logo on a dark background with a pink glow.'
    tags: ["astro", "blogging", "learning in public"]
    ---
    # My First Blog Post

    Published on: 2022-07-01

    Welcome to my _new blog_ about learning Astro! Here, I will share my learning journey as I build a new website.

    ## What I've accomplished

    1. **Installing Astro**: First, I created a new Astro project and set up my online accounts.

    2. **Making Pages**: I then learned how to make pages by creating new `.astro` files and placing them in the `src/pages/` folder.

    3. **Making Blog Posts**: This is my first blog post! I now have Astro pages and Markdown posts!

    ## What's next

    I will finish the Astro tutorial, and then keep adding more posts. Watch this space for more to come.
    ```

2. Check your browser preview again at `http://localhost:4321/posts/post-1`. You should now see content on this page. It may not yet be properly formatted, but don't worry, you will update this later in the tutorial!

3. Use your browser's Dev Tools to inspect this page. Notice that although you have not typed any HTML elements, your Markdown has been converted to HTML. You can see elements such as headings, paragraphs, and list items.
</Steps>

:::note
The information at the top of the file, inside the code fences, is called frontmatter. This data—including tags and a post image—is information *about* your post that Astro can use. It does not appear on the page automatically, but you will access it later in the tutorial to enhance your site. 
:::

## Link to your posts

<Steps>
1. Link to your first post with an anchor tag in `src/pages/blog.astro`:
    ```astro title="src/pages/blog.astro" ins={16-18}
    ---
    ---
    <html lang="en">
      <head>
        <meta charset="utf-8"/>
        <meta name="viewport" content="width=device-width" />
        <title>Astro</title>
      </head>
      <body>
        <a href="/">Home</a>
        <a href="/about/">About</a>
        <a href="/blog/">Blog</a>

        <h1>My Astro Learning Blog</h1>
        <p>This is where I will post about my journey learning Astro.</p>
        <ul>
          <li><a href="/posts/post-1/">Post 1</a></li>
        </ul>
      </body>
    </html>
    ```

2. Now, add two more files in `src/pages/posts/`: `post-2.md` and `post-3.md`. Here is some sample code you can copy and paste into your files, or, you can create your own!

    ```md title="src/pages/posts/post-2.md"
    ---
    title: My Second Blog Post
    author: Astro Learner
    description: "After learning some Astro, I couldn't stop!"
    image: 
        url: "https://docs.astro.build/assets/arc.webp"
        alt: "The Astro logo on a dark background with a purple gradient arc."
    pubDate: 2022-07-08
    tags: ["astro", "blogging", "learning in public", "successes"]
    ---
    After a successful first week learning Astro, I decided to try some more. I wrote and imported a small component from memory!
    ```

    ```md title="src/pages/posts/post-3.md"
    ---
    title: My Third Blog Post
    author: Astro Learner
    description: "I had some challenges, but asking in the community really helped!"
    image: 
        url: "https://docs.astro.build/assets/rays.webp"
        alt: "The Astro logo on a dark background with rainbow rays."
    pubDate: 2022-07-15
    tags: ["astro", "learning in public", "setbacks", "community"]
    ---
    It wasn't always smooth sailing, but I'm enjoying building with Astro. And, the [Discord community](https://astro.build/chat) is really friendly and helpful!
    ```

3. Add links to these new posts:

    ```astro title="src/pages/blog.astro" ins={18-19}
    ---
    ---
    <html lang="en">
      <head>
        <meta charset="utf-8"/>
        <meta name="viewport" content="width=device-width" />
        <title>Astro</title>
      </head>
      <body>
        <a href="/">Home</a>
        <a href="/about/">About</a>
        <a href="/blog/">Blog</a>

        <h1>My Astro Learning Blog</h1>
        <p>This is where I will post about my journey learning Astro.</p>
        <ul>
          <li><a href="/posts/post-1/">Post 1</a></li>
          <li><a href="/posts/post-2/">Post 2</a></li>
          <li><a href="/posts/post-3/">Post 3</a></li>
        </ul>
      </body>
    </html>
    ```

4. Check your browser preview and make sure that:

    All your links for Post 1, Post 2, and Post 3 lead to a working page on your site. (If you find a mistake, check your links on `blog.astro` or your Markdown file names.)
</Steps>


<Box icon="question-mark">
### Test your knowledge

1. Content in a Markdown (`.md`) file is converted to:
    <MultipleChoice>
        <Option isCorrect>HTML</Option>
        <Option>CSS</Option>
        <Option>JavaScript</Option>
    </MultipleChoice>
</Box>

<Box icon="check-list">
## Checklist

<Checklist>
- [ ] I can create a new folder within `src/pages/` for my blog posts.
- [ ] I can create a new Markdown (`.md`) blog post file.
- [ ] I understand that Markdown is another language that, like Astro, produces HTML in my browser.
</Checklist>
</Box>

### Resources

- [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/)  <Badge class="neutral-badge" text="external" />

- [What are browser developer tools? MDN](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools)  <Badge class="neutral-badge" text="external" />

- [YAML frontmatter](https://assemble.io/docs/YAML-front-matter.html)  <Badge class="neutral-badge" text="external" />
